ParcelAddress API
Search for Address
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/addresses
Production:
https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses
Resource Description
Returns a list of suggested domestic addresses for an address fragment.
Resource Information
Attribute | Detail |
---|---|
Response Format | JSON |
Requires Authentication | Yes |
Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Please note that all request parameters should be in lower case.
Request Parameters
Field Name | Description | Mand | Example |
---|---|---|---|
count | The number of matching address records to be returned. Note that the maximum value for the parameter is 10. | Yes | 10 |
q | Address fragment to search for suggestions. Valid input characters for this parameter include alphanumeric characters and a forward slash ('/'). All other characters will be ignored. | Yes | 151 Vic |
Sample Request
https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses?q=queen&count=5
Business Rules
The following business rules are applied on each /addresses request:
Name | Description |
---|---|
BR001 | The address fragment (parameter โqโ) must contain at least 4 characters after the leading and following spaces are removed by the API code. If less than 4 characters, an error message will be returned to the requester. |
BR002 | If no count value is provided, a default number of responses is returned. The default is set to 10 records. |
BR003 | If the count value provided is greater than 10 and there are more than 10 addresses matching the address fragment, only 10 address records will be returned to the merchant. |
Response Parameters
The following lists the required fields in the /addresses response message.
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | true |
addresses | Contains array of address objects. The number of object will not exceed the โCountโ value defined. | Yes if success = true | See Address Object below |
message_id | Unique identifier for the response message | Yes | 8b93211c-bffb-4ec9-bd1c-790edbd07691 |
Address Object
The following lists the fields in the address object.
Field Name | Description | Mand | Example |
---|---|---|---|
full_address | Human-readable format of the address | Yes if success = true | 151 Victoria Road, Saint Clair, Dunedin 9012 |
address_id | A unique id for representing the address | Yes | 949793 |
dpid | Delivery point identifier | No | 1376601 |
Error Response Elements
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | false |
errors | Error object with error details | Yes if success =false | See Error Object Parameters below |
message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
Field Name | Description | Example |
---|---|---|
code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
message | Description of error code | Invalid Parameter(s) |
details | Description of specific error | Address prefix must be at least 4 characters, not including spaces at the beginning or end. |
HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
Code | Message |
---|---|
200 | Success |
400 | Bad request |
401 | Unauthorized |
403 | Forbidden |
409 | Invalid request |
500 | System unavailable |
Error Codes
Code | Message |
---|---|
200001 | Partial results returned, not all system(s) have responded |
200002 | All sources responded, data may be incomplete |
400001 | Parameter(s) missing |
400002 | Invalid parameter(s) |
400003 | Non mutually exclusive parameters detected |
401001 | Unauthorised access, please contact administrator |
500001 | General Exception |
500002 | System(s) offline |
Sample Response
Success Sample:
{
"success": true,
"addresses": [
{
"full_address": "392 Ellerslie-Panmure Highway, Mount Wellington, Auckland 1060",
"address_id": "1670975",
"dpid": "1376601"
},
{
"full_address": "392E Ellerslie-Panmure Highway, Mount Wellington, Auckland 1060",
"address_id": "1064190",
"dpid": "1611011"
}
],
"message_id": "f01f008a-2a37-429b-8784-b252f56e060a"
}
Failure Sample:
{
"success": false,
"errors": [ {
"code": "400002",
"message": "Invalid parameter(s)",
"details": "Address prefix must be at least 4 characters, not including spaces at the beginning or end."
}],
"message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}